CVAR Class

The CVAR class implements a VARIANT data type. The variant data type is a tagged union that can be used to represent any other data type. While lacking in efficiency, they are heavily used in COM Automation for its flexibility. The main purpose of the CVAR class is to make its use as easy as possible when you need to use them to work with COM Automation objects.

Include file: CVAR.INC.

Name	Description
Constructors	Initialize the class with the specified value.
Operators	Procedures that perform a certain function with their operands.
vType	Returns the VARIANT type.
bstr	Extracts the content of the underlying variant and returns it as a CBSTR.
sptr	Returns the address of the underlying variant. Same as vptr but without clearing the variant.
vptr	Clears the CVAR and returns the address of the underlying variant.
wstr	Extracts the content of the underlying variant and returns it as a CWSTR.
Attach	Attaches a variant to the class.
Detach	Detaches the variant data from this class and transfers ownership to the passed variant.
ChangeType	Converts the variant from one type to another.
ChangeTypeEx	Converts the variant from one type to another.
GetDim	Gets the number of dimensions in the array.
GetLBound	Gets the lower bound for the specified dimension of the safe array.
GetUBound	Gets the upper bound for the specified dimension of the safe array.
GetElementCount	Gets the number of elements in the array.
DecToCY	Converts a CVAR of type decimal to a CY structure.
DecToDouble	Converts a CVAR of type decimal to a double.
Round	Rounds a variant to the specified number of decimal places.
FormatNumber	Formats a CVAR containing numbers into a string form.
GetBooleanElem	Extracts a single boolean element from a safe array of booleans.
GetDoubleElem	Extracts a single DOUBLE element from a safe array of doubles.
GetLongElem	Extracts a single LONG element from a safe array of longs.
GetLongIntElem	Extracts a single LONGINT element from a safe array of long integers.
GetShortElem	Extracts a single SHORT element from a safe array of shorts.
GetStringElem	Extracts a single BSTR element from a safe array of unicode strings.
GetULongElem	Extracts a single ULONG element from a safe array of unsigned longs.
GetULongIntElem	Extracts a single ULONGINT element from a safe array of unsigned long integers.
GetUShortElem	Extracts a single USHORT element from a safe array of unsigned shorts.
GetVariantElem	Extracts a single Variant element from a safe array of variants.
Put	Assigns values to a CVAR.
PutNull	Assigns a null value.
PutBool	Assigns a boolean value.
PutBoolean	Assigns a boolean value.
PutByte	Assigns a byte value.
PutUByte	Assigns an ubyte value.
PutShort	Assigns a short value.
PutUShort	Assigns an ushort value.
PutInt	Assigns an int_ value.
PutUInt	Assigns an uint value.
PutLong	Assigns a long value.
PutULong	Assigns an ulong value.
PutLongInt	Assigns a longint value.
PutULongInt	Assigns an ulongint value.
PutSingle	Assigns a single value.
PutFloat	Assigns a single value.
PutDouble	Assigns a double value.
PutBooleanArray	Initializes CVAR from an array of Boolean values.
PutShortArray	Initializes CVAR from an array of signed 16-bit integer values.
PutUShortArray	Initializes CVAR from an array of unsigned 16-bit integer values.
PutLongArray	Initializes CVAR from an array of signed 32-bit integer values.
PutULongArray	Initializes CVAR from an array of 32-bit unsigned integer values.
PutLongIntArray	Initializes CVAR from an array of signed 64-bit integer values.
PutULongIntArray	Initializes CVAR from an array of unsigned 64-bit integer values.
PutDoubleArray	Initializes CVAR from an array of unsigned 64-bit integer values.
PutStringArray	Initializes CVAR from an array of unsigned 64-bit integer values.
PutBuffer	Initializes CVAR with the contents of a buffer.
PutDateString	Initializes CVAR VT_DATE from a string.
PutDec	Initializes CVAR with the contents of a DECIMAL structure.
PutDecFromCY	Converts a currency value to a variant of type VT_DECIMAL.
PutDecFromDouble	Converts a double value to a variant of type VT_DECIMAL.
PutDecFromStr	Initializes CVAR as VT_DECIMAL from a string.
PutFileTime	Initializes CVAR with the contents of a FILETIME structure.
PutFileTimeArray	Initializes CVAR with an array of FILETIME structures.
PutGuid	Initializes CVAR from a GUID.
PutPropVariant	Initializes CVAR from the contents of a PROPVARIANT structure.
PutRecord	Initializes CVAR with a reference to an UDT.
PutRef	Assigns a value by reference (a pointer to a variable).
PutResource	Initializes the CVAR based on a string resource imbedded in an executable file.
PutSafeArray	Initializes CVAR from a safe array.
PutStrRet	Initializes CVAR with string stored in a STRRET structure.
PutSystemTime	Initializes CVAR with the contents of a SYSTEMTIME structure.
PutUtf8	Initializes CVAR with the contents of an UTF-8 string.
PutVariantArrayElem	Initializes CVAR with a value stored in another VARIANT structure.
PutVbDate	Initializes CVAR with the contents of a DATE value.
ToBooleanArray	Extracts an array of boolean values from CVAR.
ToBooleanArrayAlloc	Extracts an array of boolean values from CVAR.
ToBstr	Extracts the content of the underlying variant and returns it as a CBSTR.
ToBuffer	Extracts the contents of a CVAR of type VT_ARRRAY OR VT_UI1 to a buffer.
ToBuffer (STRING)	Extracts the contents of a CVAR of type VT_ARRRAY OR VT_UI1 to a string used as a buffer.
ToDosDateTime	Extracts a date and time value in Microsoft MS-DOS format from a CVAR of type VT_DATE.
ToDoubleArray	Extracts an array of DOUBLE values from CVAR.
ToDoubleArrayAlloc	Extracts an array of DOUBLE values from CVAR.
ToFileTime	Returns the contents of a CVAR of type VT_DATE as a FILETIME structure.
ToGuid	Returns the contents of a CVAR containing a GUID string as a GUID structure.
ToGuidBStr	Returns the contents of a CVAR containing a GUID string as an unicode GUID string.
ToGuidStr	Returns the contents of a CVAR containing a GUID string as an unicode GUID string.
ToGuidWStr	Returns the contents of a CVAR containing a GUID string as an unicode GUID string.
ToLongArray	Extracts an array of LONG values from CVAR.
ToLongArrayAlloc	Extracts an array of LONG values from CVAR.
ToLongIntArray	Extracts an array of LONGINT values from CVAR.
ToLongIntArrayAlloc	Extracts an array of LONGINT values from CVAR.
ToShortArray	Extracts an array of Int16 values from CVAR.
ToShortArrayAlloc	Extracts an array of SHORT values from CVAR.
ToStr	Extracts the content of the underlying variant and returns it as a CWSTR.
ToStringArray	Extracts data from a vector structure into a PWSTR array.
ToStringArrayAlloc	Extracts an array of PWSTR values from CVAR.
ToStrRet	Returns the contents of a CVAR of type VT_BSTR to a STRRET stucture.
ToSystemTime	Returns the contents of CVAR of type VT_DATE as a FILETIME structure.
ToULongArray	Extracts an array of ULONG values from CVAR.
ToULongArrayAlloc	Extracts an array of ULONG values from CVAR.
ToULongIntArray	Extracts an array of ULONGINT values from CVAR.
ToULongIntArrayAlloc	Extracts an array of ULONGINT values from CVAR.
ToUShortArray	Extracts an array of USHORT values from CVAR.
ToUShortArrayAlloc	Extracts an array of USHORT values from CVAR.
ToUtf8	Returns the contents of a CVAR containing a BSTR as an UTF-8 encoded string.
ToVbDate	Returns the contents of a CVAR of type VT_DATE as a DATE value.
ToWStr	Extracts the content of the underlying variant and returns it as a CWSTR.

Numeric Conversions

Name	Description
ValDouble	Converts the variant to a floating point number (DOUBLE).
ValInt	Converts the variant to a signed 32-bit integer (LONG).
ValLong	Converts the variant to a signed 32-bit integer (LONG).
ValLongInt	Converts the variant to a signed 64-bit integer (LONGINT).
Value	Converts the variant to a floating point number (DOUBLE).
ValUInt	Converts the variant to a 32.bit unsigned integer (ULONG).
ValULong	Converts the variant to a 32-bit unsigned integer (ULONG).
ValULongInt	Converts the variant to a 64-bit unsigned integer (ULONGINT).

Helper Procedures

Name	Description
AfxCVarToStr	Extracts the contents of a CVAR to a CWSTR.
AfxCVariantToBuffer	Extracts the contents of a variant that contains an array of bytes.
AfxCVarOptPrm	Returns a CVAR suitable to be used with optional parameters.

Constructors

Creates a an instance of the CVAR class.

CONSTRUCTOR
CONSTRUCTOR (BYREF cv AS CVAR)
CONSTRUCTOR (BYVAL v AS VARIANT)
CONSTRUCTOR (BYREF wsz AS WSTRING)
CONSTRUCTOR (BYREF cws AS CWSTR)
CONSTRUCTOR (BYREF cbs AS CBSTR)
CONSTRUCTOR (BYVAL pvar AS VARIANT PTR)
CONSTRUCTOR (BYVAL cy AS CURRENCY)
CONSTRUCTOR (BYVAL dec AS DECIMAL)
DECLARE CONSTRUCTOR (BYVAL b AS BOOLEAN)
CONSTRUCTOR (BYREF pDisp AS IDispatch PTR, BYVAL fAddRef AS BOOLEAN = FALSE)
CONSTRUCTOR (BYREF pUnk AS IUnknown PTR, BYVAL fAddRef AS BOOLEAN = FALSE)
CONSTRUCTOR (BYVAL _value AS LONGINT, BYVAL _vType AS WORD = VT_I4)
CONSTRUCTOR (BYVAL _value AS DOUBLE, BYVAL _vType AS WORD = VT_R8)
CONSTRUCTOR (BYVAL _value AS LONGINT, BYREF strType AS STRING)
CONSTRUCTOR (BYVAL _value AS DOUBLE, BYREF strType AS STRING)
CONSTRUCTOR (BYVAL _pvar AS ANY PTR, BYVAL _vType AS WORD)
CONSTRUCTOR (BYVAL _pvar AS ANY PTR, BYREF strType AS STRING)

Parameter	Description
cv	A CVAR.
v	A VARIANT.
pvar	Pointer to a VARIANT.
cy	A currency structure.
dec	A decimal structure.
b	A boolean value (TRUE or FALSE).
pwsz	Pointer to an unicode string. You can also pass a Free Basic ansi string or a string literal.
cbs	A CBSTR.
cws	A CWSTR.
pDisp	Pointer to a DISPATCH interface.
pUnk	Pointer to a UNKNOWN interface.
_value	A numeric value or variable.
_pvar	Pointer to a variable. This will create a VT_BYREF variant of the specified type.
_vtype	The variant type, e.g. VT_I4, VT_UI4.
strType	The variant type as a string: "BOOL", "BYTE", "UBYTE", "SHORT", "USHORT, "INT", UINT", "LONG", "ULONG", "LONGINT", "SINGLE, "DOUBLE", "NULL".
fAddRef	TRUE or FALSE. If TRUE, increases the reference count of the passed interface.

Operators

Procedures that perform a certain function with their operands. They do the same actions that the native FreeBasic operators but with variants. For detailed descriptions see the FreeBasic documentation.

Global Operators

OPERATOR & (BYREF cv1 AS CVAR, BYREF cv2 AS CVAR) AS CVAR
OPERATOR * (BYREF cv AS CVAR) AS VARIANT PTR

Cast Operators

OPERATOR Cast () AS VARIANT
OPERATOR Cast () AS VARIANT PTR

Assignment operators

OPERATOR Let (BYREF cv AS CVAR)
OPERATOR Let (BYVAL v AS VARIANT)
OPERATOR Let (BYVAL pvar AS VARIANT PTR)
OPERATOR Let (BYVAL cy AS CURRENCY)
OPERATOR Let (BYVAL dec AS DECIMAL)
OPERATOR Let (BYVAL b AS BOOLEAN)
OPERATOR Let (BYREF cbs AS CBSTR)
OPERATOR Let (BYREF cws AS CWSTR)
OPERATOR Let (BYREF pDisp AS IDispatch PTR)
OPERATOR Let (BYREF pUnk AS IUnknown PTR)
OPERATOR Let (BYVAL _value AS LONGINT)
OPERATOR Let (BYVAL _value AS DOUBLE)
OPERATOR += (BYREF cv AS CVAR)
OPERATOR -= (BYREF cv AS CVAR)
OPERATOR *= (BYREF cv AS CVAR)
OPERATOR /= (BYREF cv AS CVAR)
OPERATOR \= (BYREF cv AS CVAR)
OPERATOR Mod= (BYREF cv AS CVAR)
OPERATOR Imp= (BYREF cv AS CVAR)
OPERATOR Eqv= (BYREF cv AS CVAR)
OPERATOR ^= (BYREF cv AS CVAR)

Arithmetic operators

OPERATOR + (BYREF cv1 AS CVAR, BYREF cv2 AS CVAR) AS CVAR
OPERATOR - (BYREF cv1 AS CVAR, BYREF cv2 AS CVAR) AS CVAR
OPERATOR * (BYREF cv1 AS CVAR, BYREF cv2 AS CVAR) AS CVAR
OPERATOR / (BYREF cv1 AS CVAR, BYREF cv2 AS CVAR) AS CVAR
OPERATOR \ (BYREF cv1 AS CVAR, BYREF cv2 AS CVAR) AS CVAR
OPERATOR ^ (BYREF cv1 AS CVAR, BYREF cv2 AS CVAR) AS DOUBLE
OPERATOR Mod (BYREF cv1 AS CVAR, BYREF cv2 AS CVAR) AS INTEGER
OPERATOR - (BYREF cv AS CVAR) AS CVAR

Relational operators

OPERATOR = (BYREF cv1 AS CVAR, BYREF cv2 AS CVAR) AS BOOLEAN
OPERATOR <> (BYREF cv1 AS CVAR, BYREF cv2 AS CVAR) AS BOOLEAN
OPERATOR < (BYREF cv1 AS CVAR, BYREF cv2 AS CVAR) AS BOOLEAN
OPERATOR > (BYREF cv1 AS CVAR, BYREF cv2 AS CVAR) AS BOOLEAN
OPERATOR <= (BYREF cv1 AS CVAR, BYREF cv2 AS CVAR) AS BOOLEAN
OPERATOR >= (BYREF cv1 AS CVAR, BYREF cv2 AS CVAR) AS BOOLEAN

Bitwise operators

OPERATOR And (BYREF cv1 AS CVAR, BYREF cv2 AS CVAR) AS INTEGER
OPERATOR Eqv (BYREF cv1 AS CVAR, BYREF cv2 AS CVAR) AS INTEGER
OPERATOR Imp (BYREF cv1 AS CVAR, BYREF cv2 AS CVAR) AS INTEGER
OPERATOR Not (BYREF cv AS CVAR) AS INTEGER
OPERATOR Or (BYREF cv1 AS CVAR, BYREF cv2 AS CVAR) AS INTEGER
OPERATOR Xor (BYREF cv1 AS CVAR, BYREF cv2 AS CVAR) AS INTEGER

vType

Returns the VARIANT type.

FUNCTION vType () AS VARTYPE

The following table shows the available data types and where these values can be used.

Type	Description	VARIANT	Typedesc	Property set	Safe array
VT_EMPTY	Not specified.	X		X
VT_NULL	Null.	X		X
VT_I1	BYTE. A character.	X	X	X	X
VT_UI1	UBYTE. An unsigned character.	X	X	X	X
VT_I2	SHORT. A 2-byte integer.	X	X	X	X
VT_UI2	USHORT. An unsigned short.	X	X	X	X
VT_I4	LONG. A 4-byte integer.	X	X	X	X
VT_UI4	ULONG. An unsigned long.	X	X	X	X
VT_I8	LONGINT. A 64-bit integer.	X	X	X	X
VT_UI8	ULONGINT. A 64-bit unsigned integer.	X	X	X	X
VT_INT	LONG. An integer.	X	X	X	X
VT_UINT	ULOG. An unsigned integer.	X	X		X
VT_R4	SINGLE. A 4-byte real.	X	X	X	X
VT_R8	DOUBLE. A 8-byte real.	X	X	X	X
VT_CY	CY. Currency.	X	X	X	X
VT_DATE	DOUBLE. A date.	X	X	X	X
VT_BSTR	BSTR. A string.	X	X	X	X
VT_DISPATCH	IDispatch PTR. An IDispatch pointer.	X	X		X
VT_ERROR	SCODE. An SCODE value.	X	X	X	X
VT_BOOL	BOOLEAN. A Boolean value (True = -1, False = 0)	X	X	X	X
VT_VARIANT	VARIANT PTR. A variant pointer.	X	X	X	X
VT_UNKNOWN	IUnknown PTR. An IUnknown pointer.	X	X		X
VT_DECIMAL	DECIMAL PTR. A 16-byte fixed-pointer value.	X	X		X
VT_VOID	NULL. A C-style void.			X
VT_HRESULT	HRESULT. An HRESULT value.			X
VT_PTR	A pointer type.			X
VT_SAFEARRAY	SAFEARRAY PTR. A safe array. Use VT_ARRAY in VARIANT.		X
VT_CARRAY	A C-style array.		X
VT_USERDEFINED	A user-defined type.			X
VT_LPSTR	ZSTRING. A null-terminated string.		X	X
VT_LPWSTR	WSTRING. A wide null-terminated string.		X	X
VT_RECORD	A user-defined type.	X	X		X
VT_INT_PTR	A signed machine register size width.			X
VT_UINT_PTR	An unsigned machine register size width.			X
VT_FILETIME	FILETIME. A FILETIME value.			X
VT_BLOB	Length-prefixed bytes.			X
VT_STREAM	IStream PTR. The name of the stream follows.			X
VT_STORAGE	The name of the storage follows.			X
VT_STREAMED_OBJECT	The stream contains an object.			X
VT_STORED_OBJECT	The storage contains an object.			X
VT_BLOB_OBJECT	The blob contains an object.			X
VT_CF	A clipboard format.			X
VT_CLSID	CLSID. A class ID.			X
VT_VERSIONED_STREAM	A stream with a GUID version.			X
VT_BSTR_BLOB	Reserved for system use.
VT_VECTOR	A simple counted array.			X
VT_ARRAY	SAFEARRAY PTR. A SAFEARRAY pointer.	X
VT_BYREF	A void pointer for local use.	X
VT_RESERVED	Reserved.
VT_ILLEGAL
VT_ILLEGALMASKED
VT_TYPEMASK

bstr

Extracts the content of the underlying variant and returns it as a CBSTR.

FUNCTION bstr () AS CBSTR

sptr

Returns the address of the underlying variant. Same as vptr but without clearing the variant.

FUNCTION sptr () AS VARIANT PTR

vptr

Clears the CVAR and returns the address of the underlying variant. Can be used to pass the variant to an OUT BYVAL VARIANT PTR parameter. If we pass a CVAR to a function with an OUT variant parameter without first clearing the contents of the CVAR, we may have a memory leak.

FUNCTION vptr () AS VARIANT PTR

wstr

Extracts the content of the underlying variant and returns it as a CWSTR.

FUNCTION wstr () AS CWSTR

Attach

Attaches a variant to the class.

FUNCTION Attach (BYVAL pvar AS VARIANT PTR) AS HRESULT
FUNCTION Attach (BYREF v AS VARIANT) AS HRESULT

Parameter	Description
pvar	Pointer to the variant to attach.
v	The variant to attach.

Remark

Marks the source variant as VT_EMPTY instead of clearing it with VariantClear because we aren't making a duplicate of the contents, but transfering ownership.

Return value

Returns S_OK (0) or an HRESULT error code.

Detach

Detaches the variant data from this class and transfers ownership to the passed variant.

FUNCTION Detach (BYVAL pvar AS VARIANT PTR) AS HRESULT
FUNCTION Detach (BYREF v AS VARIANT) AS HRESULT

Parameter	Description
pvar	Pointer to the variant where the contents of the variant data will be moved.
v	Variant where the contents of the variant data will be moved.

Remark

This method transfers ownership of the underlying variant and marks it as empty.

Return value

Returns S_OK (0) or an HRESULT error code.

ChangeType

Converts the variant from one type to another.

FUNCTION ChangeType (BYVAL vtNew AS VARTYPE, BYVAL wFlags AS USHORT = 0) AS HRESULT

vtNew

The new variant type.

wFlags

VARIANT_NOVALUEPROP : Prevents the function from attempting to coerce an object to a fundamental type by getting the Value property. Applications should set this flag only if necessary, because it makes their behavior inconsistent with other applications.
VARIANT_ALPHABOOL : Converts a VT_BOOL value to a string containing either "True" or "False".
VARIANT_NOUSEROVERRIDE : For conversions to or from VT_BSTR, passes LOCALE_NOUSEROVERRIDE to the core coercion routines.
VARIANT_LOCALBOOL : For conversions from VT_BOOL to VT_BSTR and back, uses the language specified by the locale in use on the local computer.

Return value

Returns S_OK (0) or an HRESULT error code.

ChangeTypeEx

Converts the variant from one type to another.

FUNCTION ChangeTypeEx (BYVAL vtNew AS VARTYPE, BYVAL lcid AS LCID = 0, BYVAL wFlags AS USHORT = 0) AS HRESULT

Parameter	Description
vtNew	The new variant type.
lcid	The locale identifier. The LCID is useful when the type of the source or destination VARIANTARG is VT_BSTR, VT_DISPATCH, or VT_DATE.
wFlags	VARIANT_NOVALUEPROP : Prevents the function from attempting to coerce an object to a fundamental type by getting the Value property. Applications should set this flag only if necessary, because it makes their behavior inconsistent with other applications. VARIANT_ALPHABOOL : Converts a VT_BOOL value to a string containing either "True" or "False". VARIANT_NOUSEROVERRIDE : For conversions to or from VT_BSTR, passes LOCALE_NOUSEROVERRIDE to the core coercion routines. VARIANT_LOCALBOOL : For conversions from VT_BOOL to VT_BSTR and back, uses the language specified by the locale in use on the local computer.

Return value

Returns S_OK (0) or an HRESULT error code.

GetDim

Gets the number of dimensions in the array.

FUNCTION GetDim () AS ULONG

Return value

Returns the number of dimensions for variants of type VT_ARRAY; returns 0 otherwise.

GetLBound

Gets the lower bound for the specified dimension of the safe array.

FUNCTION GetLBound (BYVAL nDim AS UINT = 1) AS LONG

Parameter	Description
nDim	The dimension of the array.

Return value

Returns the lower bound for the specified dimension of the safe array for variants of type VT_ARRAY; returns 0 otherwise.

GetUBound

Gets the upper bound for the specified dimension of the safe array.

FUNCTION GetUBound (BYVAL nDim AS UINT = 1) AS LONG

Parameter	Description
nDim	The dimension of the array.

Return value

Returns the upper bound for the specified dimension of the safe array for variants of type VT_ARRAY; returns 0 otherwise.

GetElementCount

Gets the number of elements in the array.

FUNCTION GetElementCount () AS ULONG

Return value

Returns the number of elements for variants of type VT_ARRAY; returns 1 otherwise.

DecToCY

Converts a CVAR of type decimal to a CY structure.

FUNCTION DecToCY () AS CY

Return value

Returns the contents of a VT_DECIMAL variant as a CY structure.

DecToDouble

Converts a CVAR of type decimal to a double.

FUNCTION DecToDouble () AS DOUBLE

Return value

Returns the contents of a VT_DECIMAL variant as a DOUBLE.

Round

Rounds a variant to the specified number of decimal places.

FUNCTION Round (BYREF cv AS CVAR, BYVAL cDecimals AS LONG) AS CVAR

Parameter	Description
cv	The CVAR to round.
cDecimals	The number of decimal places.

Return value

A CVAR containing the rounded result.

FormatNumber

Formats a CVAR containing numbers into a string form.

FUNCTION FormatNumber (BYVAL iNumDig AS LONG = -1, BYVAL ilncLead AS LONG = -2, _
   BYVAL iUseParens AS LONG = -2, BYVAL iGroup AS LONG = -2, BYVAL dwFlags AS DWORD = 0) AS CBSTR

Parameter	Description
iNumDig	The number of digits to pad to after the decimal point. Specify -1 to use the system default value.
ilncLead	Specifies whether to include the leading digit on numbers. -2 : Use the system default. -1 : Include the leading digit. 0 : Do not include the leading digit.
iUseParens	Specifies whether negative numbers should use parentheses. -2 : Use the system default. -1 : Use parentheses. 0 : Do not use parentheses.
iGroup	Specifies whether thousands should be grouped. For example 10,000 versus 10000. -2 : Use the system default. -1 : Group thousands. 0 : Do not group thousands.
dwFlags	VAR_CALENDAR_HIJRI is the only flag that can be set.

Return value

A CWSTR containing the formatted value.

Remarks

This function uses the user's default locale while calling VarTokenizeFormatString and VarFormatFromTokens.

GetBooleanElem

Extracts a single boolean element from a safe array of booleans.

FUNCTION GetBooleanElem (BYVAL iElem AS ULONG) AS BOOLEAN

Parameter	Description
iElem	The index of the element of the array.

Return value

The retrieved value.

GetDoubleElem

Extracts a single DOUBLE element from a safe array of doubles.

FUNCTION GetDoubleElem (BYVAL iElem AS ULONG) AS DOUBLE

Parameter	Description
iElem	The index of the element of the array.

Return value

The retrieved value.

GetLongElem

Extracts a single LONG element from a safe array of longs.

FUNCTION GetLongElem (BYVAL iElem AS ULONG) AS LONG

Parameter	Description
iElem	The index of the element of the array.

Return value

The retrieved value.

GetLongIntElem

Extracts a single LONGINT element from a safe array of long integers.

FUNCTION GetLongIntElem (BYVAL iElem AS ULONG) AS LONGINT

Parameter	Description
iElem	The index of the element of the array.

Return value

The retrieved value.

GetShortElem

Extracts a single SHORT element from a safe array of short integers.

FUNCTION GetShortElem (BYVAL iElem AS ULONG) AS SHORT

Parameter	Description
iElem	The index of the element of the array.

Return value

The retrieved value.

GetStringElem

Extracts a single BSTR element from a safe array of unicode strings.

FUNCTION GetStringElem (BYVAL iElem AS ULONG) AS BSTR

Parameter	Description
iElem	The index of the element of the array.

Return value

The retrieved value.

GetULongElem

Extracts a single ULONG element from a safe array of unsigned longs.

FUNCTION GetULongElem (BYVAL iElem AS ULONG) AS ULONG

Parameter	Description
iElem	The index of the element of the array.

Return value

The retrieved value.

GetULongIntElem

Extracts a single ULONGINT element from a safe array of unsigned long integers.

FUNCTION GetULongIntElem (BYVAL iElem AS ULONG) AS ULONGINT

Parameter	Description
iElem	The index of the element of the array.

Return value

The retrieved value.

GetUShortElem

Extracts a single USHORT element from a safe array of unsigned shorts.

FUNCTION GetUShortElem (BYVAL iElem AS ULONG) AS USHORT

Parameter	Description
iElem	The index of the element of the array.

Return value

The retrieved value.

GetVariantElem

Extracts a single Variant element from a safe array of variants.

FUNCTION GetVariantElem (BYVAL iElem AS ULONG) AS CVAR

Parameter	Description
iElem	The index of the element of the array.

Return value

The retrieved value.

Put

Assigns values to a CVAR.

SUB Put (BYREF wsz AS WSTRING)
SUB Put (BYREF cws AS CWSTR)
SUB Put (BYREF cbs AS CBSTR)
FUNCTION Put (BYREF cv AS CVAR) AS HRESULT
FUNCTION Put (BYVAL v AS VARIANT) AS HRESULT
FUNCTION Put (BYVAL pvar AS VARIANT PTR) AS HRESULT
FUNCTION Put (BYREF pDisp AS IDispatch PTR, BYVAL fAddRef AS BOOLEAN = FALSE) AS HRESULT
FUNCTION Put (BYREF pUnk AS IUnknown PTR, BYVAL fAddRef AS BOOLEAN = FALSE) AS HRESULT
SUB Put (BYVAL _value AS LONGINT, BYVAL _vType AS WORD = VT_I4)
SUB Put (BYVAL _value AS DOUBLE, BYVAL _vType AS WORD = VT_R8)
SUB Put (BYVAL _value AS LONGINT, BYREF strType AS STRING)
SUB Put (BYVAL _value AS DOUBLE, BYREF strType AS STRING)
SUB Put (BYVAL _pv AS ANY PTR, BYVAL _vType AS WORD)
SUB Put (BYVAL _pv AS ANY PTR, BYREF strType AS STRING)

Parameter	Description
wsz	An unicode string. You can also pass a Free Basic ansi string or a string literal.
cws	A CWSTR variable.
cbs	A CBSTR variable.
cv	A CVAR variable.
v	A VARIANT variable.
v	A VARIANT variable.
pvar	Pointer to a VARIANT variable.
pDisp	Pointer to a DISPATCH interface.
pUnk	Pointer to a UNKNOWN interface.
_pv	Pointer to a variable. This will create a VT_BYREF variant of the specified type.
_vtype	The variant type, e.g. VT_I4, VT_UI4.
strType	The variant type as a string: "BOOL", "BYTE", "UBYTE", "SHORT", "USHORT, "INT", UINT", "LONG", "ULONG", "LONGINT", "SINGLE, "DOUBLE", "NULL".
fAddRef	TRUE or FALSE. If TRUE, increases the reference count of the interface.

PutNull

Assigns a null value to the CVAR.

SUB PutNull

PutBool

Assigns a boolean value to the CVAR.

SUB PutBool (BYVAL _value AS BOOL)

PutBoolean

Assigns a boolean value to the CVAR.

SUB PutBoolean (BYVAL _value AS BOOLEAN)

PutByte

Assigns a byte value to the CVAR.

SUB PutByte (BYVAL _value AS BYTE)

PutUByte

Assigns an unsigned ubyte value to the CVAR.

SUB PutUByte (BYVAL _value AS UBYTE)

PutShort

Assigns a short integer value to the CVAR.

SUB PutShort (BYVAL _value AS SHORT)

PutUShort

Assigns an unsigned short integer value to the CVAR.

SUB PutUShort (BYVAL _value AS USHORT)

PutInt

Assigns an INT_ (long) value to the CVAR.

SUB PutInt (BYVAL _value AS INT_)

Remark

Don't confuse an INT_ (LONG) with the Free Basic INTEGER data type.

PutUInt

Assigns an UINT (unsigned long) value to the CVAR.

SUB PutUInt (BYVAL _value AS UINT)

Remark

Don't confuse an UINT (ULONG) with the Free Basic UINTEGER data type.

PutLong

Assigns a LONG value to the CVAR.

SUB PutLong (BYVAL _value AS LONG)

PutULong

Assigns a ULONG value to the CVAR.

SUB PutULong (BYVAL _value AS ULONG)

PutLongInt

Assigns a LONGINT value to the CVAR.

SUB PutULong (BYVAL _value AS LONGINT)

PutULongInt

Assigns a ULONGINT value to the CVAR.

SUB PutULongInt (BYVAL _value AS ULONGINT)

PutSingle

Assigns a SINGLE value to the CVAR.

SUB PutSingle (BYVAL _value AS SINGLE)

PutFloat

Assigns a SINGLE value to the CVAR.

SUB PutFloat (BYVAL _value AS SINGLE)

PutDouble

Assigns a DOUBLE value to the CVAR.

SUB PutDouble (BYVAL _value AS DOUBLE)

PutBooleanArray

Initializes CVAR from an array of Boolean values.

FUNCTION PutBooleanArray (BYVAL prgf AS WINBOOL PTR, BYVAL cElems AS ULONG) AS HRESULT

Parameter	Description
prgf	Pointer to source array of Boolean values.
cElems	The number of elements in the array.

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_ARRAY OR VT_BOOL variant.

PutShortArray

Initializes CVAR from an array of signed 16-bit integer values.

FUNCTION PutShortArray (BYVAL prgf AS SHORT PTR, BYVAL cElems AS ULONG) AS HRESULT

Parameter	Description
prgf	Pointer to source array of SHORT values.
cElems	The number of elements in the array.

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_ARRAY OR VT_I2 variant.

PutUshortArray

Initializes CVAR from an array of 16-bit unsigned integer values.

FUNCTION PutUshortArray (BYVAL prgf AS USHORT PTR, BYVAL cElems AS ULONG) AS HRESULT

Parameter	Description
prgf	Pointer to source array of USHORT values.
cElems	The number of elements in the array.

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_ARRAY OR VT_UI2 variant.

PutLongArray

Initializes CVAR from an array of signed 32-bit integer values.

FUNCTION PutLongArray (BYVAL prgf AS LONG PTR, BYVAL cElems AS ULONG) AS HRESULT

Parameter	Description
prgf	Pointer to source array of LONG values.
cElems	The number of elements in the array.

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_ARRAY OR VT_I4 variant.

PutULongArray

Initializes CVAR from an array of 32-bit unsigned integer values.

FUNCTION PutULongArray (BYVAL prgf AS ULONG PTR, BYVAL cElems AS ULONG) AS HRESULT

Parameter	Description
prgf	Pointer to source array of ULONG values.
cElems	The number of elements in the array.

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_ARRAY OR VT_UI4 variant.

PutLongIntArray

Initializes CVAR from an array of signed 64-bit integer values.

FUNCTION PutLongIntArray (BYVAL prgf AS LONGINT PTR, BYVAL cElems AS ULONG) AS HRESULT

Parameter	Description
prgf	Pointer to source array of LONGINT values.
cElems	The number of elements in the array.

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_ARRAY OR VT_I8 variant.

PutULongIntArray

Initializes CVAR from an array of unsigned 64-bit integer values.

FUNCTION PutULongIntArray (BYVAL prgf AS ULONGINT PTR, BYVAL cElems AS ULONG) AS HRESULT

Parameter	Description
prgf	Pointer to source array of ULONGINT values.
cElems	The number of elements in the array.

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_ARRAY OR VT_UI8 variant.

PutDoubleArray

Initializes CVAR from an array of unsigned 64-bit integer values.

FUNCTION PutDoubleArray (BYVAL prgf AS DOUBLE PTR, BYVAL cElems AS ULONG) AS HRESULT

Parameter	Description
prgf	Pointer to source array of DOUBLE values.
cElems	The number of elements in the array.

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_ARRAY OR VT_R8 variant.

PutStringArray

Initializes CVAR from an array of unicode strings.

FUNCTION PutStringArray (BYVAL prgsz AS PCWSTR, BYVAL cElems AS ULONG) AS HRESULT

Parameter	Description
prgsz	Pointer to source array of unicode strings.
cElems	The number of elements in the array.

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_ARRAY OR VT_BSTR variant.

PutBuffer

Initializes CVAR with the contents of a buffer.

FUNCTION PutBuffer (BYVAL pv AS VOID PTR, BYVAL cb AS UINT) AS HRESULT

Parameter	Description
pv	Pointer to the source buffer.
cb	The length of the buffer, in bytes.

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_ARRAY OR VT_UI1 variant.

PutDateString

Initializes CVAR VT_DATE from a string.

FUNCTION PutDateString (BYVAL pwszDate AS WSTRING PTR, BYVAL lcid AS LCID = 0, _
   BYVAL dwFlags AS ULONG = 0) AS HRESULT

Parameter	Description
pwszDate	The date value to convert, e.g. "2018-08-20 19:42".
lcid	The locale identifier.
dwFlags	One or more of the following flags. LOCALE_NOUSEROVERRIDE : Uses the system default locale settings, rather than custom locale settings. VAR_CALENDAR_HIJRI : If set then the Hijri calendar is used. Otherwise the calendar set in the control panel is used. VAR_TIMEVALUEONLY : Omits the date portion of a VT_DATE and returns only the time. Applies to conversions to or from dates. VAR_DATEVALUEONLY : Omits the time portion of a VT_DATE and returns only the date. Applies to conversions to or from dates.

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_DATE variant.

PutDec

Initializes CVAR with the contents of a DECIMAL structure.

FUNCTION PutDec (BYCAL dec AS DECIMAL) AS HRESULT

Parameter	Description
dec	A DECIMAL structure.

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_DECIMAL OR VT_BYREF variant.

PutDecFromCY

Converts a currency value to a variant of type VT_DECIMAL.

FUNCTION PutDecFromCY (BYVAL cyIn AS CY) AS HRESULT

Parameter	Description
cyIn	The currency value to convert.

Return value

This function can return one of these values.

Value	Meaning
S_OK	Success.
DISP_E_TYPEMISMATCH	The argument could not be coerced to the specified type.
E_INVALIDARG	One of the arguments is not valid.
E_OUTOFMEMORY	Insufficient memory to complete the operation.

Remarks

Creates a VT_DECIMAL variant.

PutDecFromDouble

Converts a double value to a variant of type VT_DECIMAL.

FUNCTION PutDecFromDouble (BYVAL dbIn AS DOUBLE) AS HRESULT

Parameter	Description
dbIn	The DOUBLE value to convert.

Return value

This function can return one of these values.

Value	Meaning
S_OK	Success.
DISP_E_TYPEMISMATCH	The argument could not be coerced to the specified type.
E_INVALIDARG	One of the arguments is not valid.
E_OUTOFMEMORY	Insufficient memory to complete the operation.

Remarks

Creates a VT_DECIMAL variant.

PutDecFromStr

Initializes CVAR as VT_DECIMAL from a string.

FUNCTION PutDecFromStr (BYVAL pwszIn AS WSTRING PTR, BYVAL lcid AS LCID = 0, _
   BYVAL dwFlags AS ULONG = 0) AS HRESULT

Parameter	Description
pwszIn	The string value to convert.
lcid	The locale identifier.
dwFlags	One or more of the following flags. LOCALE_NOUSEROVERRIDE : Uses the system default locale settings, rather than custom locale settings. VAR_TIMEVALUEONLY : Omits the date portion of a VT_DATE and returns only the time. Applies to conversions to or from dates. VAR_DATEVALUEONLY : Omits the time portion of a VT_DATE and returns only the date. Applies to conversions to or from dates.

Return value

This function can return one of these values.

Value	Meaning
S_OK	Success.
DISP_E_TYPEMISMATCH	The argument could not be coerced to the specified type.
E_INVALIDARG	One of the arguments is not valid.
E_OUTOFMEMORY	Insufficient memory to complete the operation.

Remarks

Creates a VT_DECIMAL variant.

PutFileTime

Initializes CVAR with the contents of a FILETIME structure.

FUNCTION PutFileTime (BYVAL pft AS FILETIME PTR) AS HRESULT

Parameter	Description
pft	Pointer to a FILETIME structure.

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_DATE variant.

PutFileTimeArray

Initializes CVAR with an array of FILETIME structures.

FUNCTION PutFileTimeArray (BYVAL prgft AS FILETIME PTR, BYVAL cElems AS ULONG) AS HRESULT

Parameter	Description
prgft	Pointer to an array of FILETIME structures.
cElems	The number of elements in the array pointed to by prgft.

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_ARRAY OR VT_DATE variant.

PutGuid

Initializes CVAR from a GUID.

FUNCTION PutGuid (BYVAL rguid AS GUID PTR) AS HRESULT

Parameter	Description
rguid	Reference to the source GUID.

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_ARRAY OR VT_UI1 variant.

PutPropVariant

Initializes CVAR from the contents of a PROPVARIANT structure.

FUNCTION PutPropVariant (BYVAL pPropVar AS PROPVARIANT PTR) AS HRESULT

Parameter	Description
pPropVar	Pointer to a source PROPVARIANT structure.

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Normally, the data stored in the PROPVARIANT is copied to the VARIANT without a datatype change. However, in the following cases, there is no direct VARIANT support for the datatype, and they are converted as shown.

VT_BLOB, VT_STREAM
Converted to VT_UNKNOWN. The punkVal member will contain a pointer to an IStream that contains the source data.

VT_LPSTR, VT_LPWSTR, VT_CLSID
Converted to VT_BSTR,

VT_FILETIME
Converted to VT_DATE.

VT_VECTOR OR x
Converted to VT_ARRAY OR x

The following types cannot be converted with this function.

VT_STORAGE
VT_BLOB_OBJECT
VT_STREAMED_OBJECT
VT_STORED_OBJECT
VT_CF
VT_VECTOR OR VT_CF

PutRecord

Initializes CVAR with a reference to an UDT.

FUNCTION PutRecord (BYVAL pIRecordInfo AS IRecordInfo PTR, BYVAL pRec AS VOID PTR) AS HRESULT

Parameter	Description
pIRecordInfo	Pointer to the IRecordInfo interface.
pRec	Pointer to the UDT.

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_RECORD variant.

PutRef

Assigns a value by reference (a pointer to a variable).

FUNCTION PutRef (BYVAL _pvar AS ANY PTR, BYVAL _vType AS WORD) AS HRESULT
FUNCTION PutRef (BYVAL _pvar AS ANY PTR, BYREF strType AS STRING) AS HRESULT

Parameter	Description
_pvar	Pointer to a variable.
_vType	Type of the variant: VT_BOOL, VT_I1, VT_UI1, VT_I2, VT_UI2, VT_INT, VT_UINT, VT_I4, VT_UI4, VT_I8, VT_UI8, VT_R4, VT_R8, VT_BSTR, VT_UNKNOWN, VT_DISPATCH, VT_DECIMAL, VT_CY, VT_DATE, VT_VARIANT, VT_SAFEARRAY, VT_ERROR.
strType	Type of the variant: "BOOL", "BYTE", "UBYTE", "SHORT", "USHORT", "INT", "UINT", "LONG", "ULONG", "LONGINT", "ULONGINT", "SINGLE", "DOUBLE", "BSTR", "UNKNOWN", "DISPATCH", "DECIMAL", "CY", "DATE", "VARIANT", "SAFEARRAY", "ERROR".

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_BYREF variant of the sepecified type.

PutResource

Initializes the CVAR based on a string resource imbedded in an executable file.

FUNCTION PutResource (BYVAL hinst AS HINSTANCE, BYVAL id AS UINT) AS HRESULT

Parameter	Description
hinst	The instance handle.
id	Integer identifier of the string to be loaded.

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_BSTR variant. If the resource does not exist, this function initializes the VARIANT as VT_EMPTY and returns a failure code.

PutSafeArray

Initializes CVAR from a safe array.

FUNCTION PutSafeArray (BYVAL parray AS SAFEARRAY PTR) AS HRESULT

Parameter	Description
parray	Pointer to safe array.

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_ARRAY variant.

PutStrRet

Initializes CVAR with the string stored in a STRRET structure.

FUNCTION PutStrRet (BYVAL pstrret AS STRRET PTR, BYVAL pidl AS PCUITEMID_CHILD) AS HRESULT

Parameter	Description
pstrret	Pointer to a STRRET structure.
pidl	PIDL of the item whose details are being retrieved.

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_BSTR variant. This function frees the resources used for the STRRET contents.

PutSystemTime

Initializes CVAR with the contents of a SYSTEMTIME structure.

FUNCTION PutSystemTime (BYVAL pst AS SYSTEMTIME PTR) AS HRESULT

Parameter	Description
pst	Pointer to a SYSTEMTIME structure.

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_DATE variant.

PutUtf8

Initializes CVAR with the contents of an UTF-8 string.

FUNCTION PutUtf8 (BYREF strUtf8 AS STRING) AS HRESULT

Parameter	Description
strUtf8	The UTF-8 encoded string.

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_BSTR variant.

PutVariantArrayElem

Initializes CVAR with a value stored in another VARIANT structure.

FUNCTION PutVariantArrayElem (BYVAL pvarIn AS VARIANT PTR, BYVAL iElem AS ULONG) AS HRESULT

Parameter	Description
pvarIn	Reference to the source VARIANT structure.
iElem	Index of one of the source VARIANT structure elements.

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

This helper function works for VARIANT structures of the following types:

VT_BSTR
VT_BOOL
VT_I2
VT_I4
VT_I8
VT_U12
VT_U14
VT_U18
VT_DATE
VT_ARRAY | (any one of VT_BSTR, VT_BOOL, VT_I2, VT_I4, VT_I8, VT_U12, VT_U14, VT_U18, VT_DATE)

Additional types may be supported in the future.

This function extracts a single value from the source VARIANT structure and uses that value to initialize the output VARIANT structure. The calling application must use VariantClear to free the VARIANT referred to by pvar when it is no longer needed.

If the source VARIANT is an array, iElem must be less than the number of elements in the array.

If the source VARIANT has a single value, iElem must be 0.

If the source VARIANT is empty, this function always returns an error code.

You can use GetElementCount to obtain the number of elements in the array or array.

PutVbDate

Initializes CVAR with the contents of a DATE value.

FUNCTION PutVbDate (BYREF vbDate AS DATE_) AS HRESULT

Parameter	Description
vbDate	The DATE value.

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_DATE variant.

ToBooleanArray

Extracts an array of boolean values from CVAR.

FUNCTION ToBooleanArray (BYVAL prgf AS WINBOOL PTR, BYVAL crgn AS ULONG) AS ULONG

Parameter	Description
prgf	Pointer to a buffer that contains crgn boolean values. When this function returns, the buffer has been initialized with elements extracted from the source VARIANT structure.
crgn	The number of elements in the buffer pointed to by prgf.

Return value

The count of WINBOOL elements extracted from the CVAR.

Remarks

This helper function is used when the calling application expects a VARIANT to hold an array that consists of a fixed number of boolean values.

If the source VARIANT is of type VT_ARRAY OR VT_BOOL, this function extracts up to crgn WINBOOL values and places them into the buffer pointed to by prgf. If the VARIANT contains more elements than will fit into the prgf buffer, this function returns 0.

ToBooleanArrayAlloc

Extracts an array of boolean values from CVAR.

FUNCTION ToBooleanArrayAlloc (BYVAL pprgf AS WINBOOL PTR PTR) AS ULONG

Parameter	Description
prgf	Pointer to a WINBOOL PTR variable that will recive a pointer to an array of WINBOOL values extracted from the source CVAR.

Return value

The count of WINBOOL elements extracted from the CVAR.

Remarks

This helper function is used when the calling application expects a CVAR to hold an array of WINBOOL values.

If CVAR is of type VT_ARRAY OR VT_BOOL, this function extracts an array of WINBOOL values into a newly allocated array. The calling application is responsible for using CoTaskMemFree to release the array pointed to by pprgf when it is no longer needed.

ToBstr

Extracts the content of the underlying variant and returns it as a CBSTR.

FUNCTION ToBstr () AS CBSTR

Return value

The contents of the variant as a CBSTR.

Example

DIM cv AS CVAR = "Test string"
DIM cbs AS CBSTR = cv.ToBstr

ToBuffer

Extracts the contents of a CVAR of type VT_ARRRAY OR VT_UI1 to a buffer.

FUNCTION ToBuffer (BYVAL pv AS VOID PTR, BYVAL cb AS UINT) AS HRESULT

Parameter	Description
pv	Pointer to a buffer of length cb bytes. When this function returns, contains the first cb bytes of the extracted buffer value.
cb	The size of the pv buffer, in bytes. The buffer should be the same size as the data to be extracted, or smaller.

Return value

Returns one of the following values:

Value	Meaning
S_OK	Data successfully extracted.
E_INVALIDARG	The VARIANT was not of type VT_ARRRAY OR VT_UI1.
E_FAIL	The VARIANT buffer value had fewer than cb bytes.

Remarks

This function is used when the calling application expects a VARIANT to hold a buffer value. The calling application should check that the value has the expected length before it calls this function.

If CVAR has type VT_ARRAY OR VT_UI1, this function extracts the first cb bytes from the structure and places them in the buffer pointed to by pv.

If the stored value has fewer than cb bytes, then function fails and the buffer is not modified.

If the value has more than cb bytes, then function succeeds and truncates the value.

To retrieve the size of the array call GetElementCount.

ToBuffer (STRING)

Extracts the contents of a CVAR of type VT_ARRRAY OR VT_UI1 to a string used as a buffer.

FUNCTION ToBuffer () AS STRING

Return value

A string with the contents of the array.

ToDosDateTime

Extracts a date and time value in Microsoft MS-DOS format from a CVAR of type VT_DATE.

FUNCTION ToDosDateTime (BYVAL pwDate AS USHORT PTR, BYVAL pwTime AS USHORT PTR) AS HRESULT

Parameter	Description
pwDate	When this function returns, contains the extracted USHORT that represents a MS-DOS date.
pwTime	When this function returns, contains the extracted contains the extracted WORD that represents a MS-DOS time.

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

This helper function is used when the calling application expects a CVAR to hold a datetime value.

If CVAR is of type VT_DATE, this function extracts the datetime value.

If CVAR is not of type VT_DATE, the function attempts to convert the value in the VARIANT structure into the right format. If a conversion is not possible, it returns a failure code.

ToDoubleArray

Extracts an array of DOUBLE values from CVAR.

FUNCTION ToDoubleArray (BYVAL prgn AS DOUBLE PTR, BYVAL crgn AS ULONG) AS ULONG

Parameter	Description
prgn	Pointer to a buffer that contains crgn DOUBLE variables. When this function returns, the buffer has been initialized with DOUBLE elements extracted from CVAR.
crgn	The number of elements in the buffer pointed to by prgn.

Return value

This helper function is used when the calling application expects a VARIANT to hold an array that consists of a fixed number of DOUBLE values.

If the source VARIANT is of type VT_ARRAY OR VT_R8, this function extracts up to crgn DOUBLE values and places them into the buffer pointed to by prgn. If the VARIANT contains more elements than will fit into the prgn buffer, this function returns 0.

ToDoubleArrayAlloc

Extracts an array of DOUBLE values from CVAR.

FUNCTION ToDoubleArrayAlloc (BYVAL pprgn AS ULONGINT PTR PTR) AS ULONG

Parameter	Description
pprgf	Pointer to a DOUBLE PTR variable that will recive a pointer to an array of DOUBLE values extracted from the source CVAR.

Return value

The count of DOUBLE elements extracted from the CVAR.

Remarks

This helper function is used when the calling application expects a CVAR to hold an array of DOUBLE values.

If CVAR is of type VT_ARRAY OR VT_R8, this function extracts an array of DOUBLE values into a newly allocated array. The calling application is responsible for using CoTaskMemFree to release the array pointed to by pprgn when it is no longer neede

ToFileTime

Returns the contents of a CVAR of type VT_DATE as a FILETIME structure.

FUNCTION ToFileTime (BYVAL stfOut AS AFX_PSTIME_FLAGS) AS FILETIME

Parameter	Description
stfOut	Specifies one of the following time flags: PSTF_UTC (0) : Indicates coordinated universal time. PSTF_LOCAL (1) : Indicates local time.

Return value

A FILETIME structure.

ToGuid

Returns the contents of a CVAR containing a GUID string as a GUID structure.

FUNCTION ToGuid () AS GUID

Return value

Returns the contents of a CVAR containing a GUID string as an unicode GUID string.

ToGuidBStr

Returns the contents of a CVAR containing a GUID string as an unicode GUID string.

FUNCTION ToGuidBStr () AS CBSTR

Return value

A GUID string.

ToGuidStr

Returns the contents of a CVAR containing a GUID string as an unicode GUID string.

FUNCTION ToGuidStr () AS CWSTR

Return value

A GUID string.

ToGuidWStr

Returns the contents of a CVAR containing a GUID string as an unicode GUID string.

FUNCTION ToGuidWStr () AS CWSTR

Return value

A GUID string.

ToLongArray

Extracts an array of LONG values from CVAR.

FUNCTION ToLongArray (BYVAL prgn AS LONG PTR, BYVAL crgn AS ULONG) AS ULONG

Parameter	Description
prgn	Pointer to a buffer that contains crgn LONG variables. When this function returns, the buffer has been initialized with Int32 elements extracted from CVAR.
crgn	The number of elements in the buffer pointed to by prgn.

Return value

This helper function is used when the calling application expects a VARIANT to hold an array that consists of a fixed number of Int32 values.

If the source VARIANT is of type VT_ARRAY OR VT_I4, this function extracts up to crgn Int32 values and places them into the buffer pointed to by prgn. If the VARIANT contains more elements than will fit into the prgn buffer, this function returns 0.

ToLongArrayAlloc

Extracts an array of LONG values from CVAR.

FUNCTION ToLongArrayAlloc (BYVAL pprgn AS LONG PTR PTR) AS ULONG

Parameter	Description
pprgn	Pointer to a LONG PTR variable that will recive a pointer to an array of LONG values extracted from the source CVAR.

Return value

The count of LONG elements extracted from the CVAR.

Remarks

This helper function is used when the calling application expects a CVAR to hold an array of LONG values.

If CVAR is of type VT_ARRAY OR VT_I4, this function extracts an array of LONG values into a newly allocated array. The calling application is responsible for using CoTaskMemFree to release the array pointed to by pprgn when it is no longer needed.

ToLongIntArray

Extracts an array of LONGINT values from CVAR.

FUNCTION ToLongIntArray (BYVAL prgn AS LONGINT PTR, BYVAL crgn AS ULONG) AS ULONG

Parameter	Description
prgn	Pointer to a buffer that contains crgn LONGINT variables. When this function returns, the buffer has been initialized with Int64 elements extracted from CVAR.
crgn	The number of elements in the buffer pointed to by prgn.

Return value

This helper function is used when the calling application expects a VARIANT to hold an array that consists of a fixed number of Int64 values.

If the source VARIANT is of type VT_ARRAY OR VT_UI4, this function extracts up to crgn Int64 values and places them into the buffer pointed to by prgn. If the VARIANT contains more elements than will fit into the prgn buffer, this function returns 0.

ToLongIntArrayAlloc

Extracts an array of LONGINT values from CVAR.

FUNCTION ToLongIntArrayAlloc (BYVAL pprgn AS LONGINT PTR PTR) AS ULONG

Parameter	Description
pprgn	Pointer to a LONGINT PTR variable that will recive a pointer to an array of LONGINT values extracted from the source CVAR.

Return value

The count of LONGINT elements extracted from the CVAR.

Remarks

This helper function is used when the calling application expects a CVAR to hold an array of LONGINT values.

If CVAR is of type VT_ARRAY OR VT_I8, this function extracts an array of LONGINT values into a newly allocated array. The calling application is responsible for using CoTaskMemFree to release the array pointed to by pprgn when it is no longer needed.

ToShortArray

Extracts an array of Int16 values from CVAR.

FUNCTION ToShortArray (BYVAL prgn AS SHORT PTR, BYVAL crgn AS ULONG) AS ULONG

Parameter	Description
prgn	Pointer to a buffer that contains crgn Int16 variables. When this function returns, the buffer has been initialized with Int16 elements extracted from CVAR.
crgn	The number of elements in the buffer pointed to by prgn.

Return value

The count of Int16 elements extracted from the CVAR.

Remarks

This helper function is used when the calling application expects a VARIANT to hold an array that consists of a fixed number of Int16 values.

If the source VARIANT is of type VT_ARRAY OR VT_I2, this function extracts up to crgn Int16 values and places them into the buffer pointed to by prgn. If the VARIANT contains more elements than will fit into the prgn buffer, this function returns 0.

ToShortArrayAlloc

Extracts an array of SHORT values from CVAR.

FUNCTION ToShortArrayAlloc (BYVAL pprgn AS SHORT PTR PTR) AS ULONG

Parameter	Description
pprgn	Pointer to a SHORT PTR variable that will recive a pointer to an array of SHORT values extracted from the source CVAR.

Return value

The count of SHORT elements extracted from the CVAR.

Remarks

This helper function is used when the calling application expects a CVAR to hold an array of SHORT values.

If CVAR is of type VT_ARRAY OR VT_I2, this function extracts an array of SHORT values into a newly allocated array. The calling application is responsible for using CoTaskMemFree to release the array pointed to by pprgn when it is no longer needed.

ToStr

Extracts the content of the underlying variant and returns it as a CWSTR.

FUNCTION ToStr () AS CWSTR

Return value

The contents of the variant as a CWSTR.

Example

DIM cv AS CVAR = "Test string"
DIM cws AS CWSTR = cv.ToStr

ToStringArray

Extracts data from a vector structure into a PWSTR array.

FUNCTION ToStringArray (BYVAL prgsz AS PWSTR, BYVAL crgsz AS ULONG) AS ULONG

Parameter	Description
prgsz	Pointer to a buffer that contains crgn PWSTR values. When this function returns, the buffer has been initialized with elements extracted from the source VARIANT structure.
crgsz	The number of elements in the buffer pointed to by prgsz.

Return value

The count of PWSTR elements extracted from the CVAR.

Remarks

This helper function is used when the calling application expects a CVAR to hold an array of PWSTR values. If the VARIANT contains more elements than will fit into the prgsz buffer, this function returns 0.

ToStringArrayAlloc

Extracts an array of PWSTR values from CVAR.

FUNCTION ToStringArrayAlloc (BYVAL pprgsz AS PWSTR PTR) AS ULONG

Parameter	Description
pprgsz	Pointer to a PWSTR PTR variable that will recive a pointer to an array of PWSTR values extracted from the source CVAR.

Return value

The count of PWSTR elements extracted from the CVAR.

Remarks

This helper function is used when the calling application expects a CVAR to hold an array of PWSTR values.

This function extracts an array of PWSTR values into a newly allocated array. The calling application is responsible for using CoTaskMemFree to free the memory used by each of the strings and to release the array pointed to by pprgn when it is no longer needed.

ToStrRet

Returns the contents of a CVAR of type VT_BSTR to a STRRET stucture.

FUNCTION ToStrRet () AS STRRET

Return value

A STRRET structure.

ToSystemTime

Returns the contents of CVAR of type VT_DATE as a FILETIME structure.

FUNCTION ToSystemTime () AS SYSTEMTIME

Return value

A SYSTEMTIME structure.

ToULongArray

Extracts an array of ULONG values from CVAR.

FUNCTION ToULongArray (BYVAL prgn AS ULONG PTR, BYVAL crgn AS ULONG) AS ULONG

Parameter	Description
prgn	Pointer to a buffer that contains crgn ULONG variables. When this function returns, the buffer has been initialized with UInt32 elements extracted from CVAR.
crgn	The number of elements in the buffer pointed to by prgn.

Return value

The count of UInt32 elements extracted from the CVAR.

Remarks

This helper function is used when the calling application expects a VARIANT to hold an array that consists of a fixed number of UInt32 values.

If the source VARIANT is of type VT_ARRAY OR VT_UI4, this function extracts up to crgn UInt32 values and places them into the buffer pointed to by prgn. If the VARIANT contains more elements than will fit into the prgn buffer, this function returns 0.

ToULongArrayAlloc

Extracts an array of ULONG values from CVAR.

FUNCTION ToULongArrayAlloc (BYVAL pprgn AS ULONG PTR PTR) AS ULONG

Parameter	Description
pprgn	Pointer to a ULONG PTR variable that will recive a pointer to an array of ULONG values extracted from the source CVAR.

Return value

The count of ULONG elements extracted from the CVAR.

Remarks

This helper function is used when the calling application expects a CVAR to hold an array of ULONG values.

If CVAR is of type VT_ARRAY OR VT_UI4, this function extracts an array of ULONG values into a newly allocated array. The calling application is responsible for using CoTaskMemFree to release the array pointed to by pprgn when it is no longer needed.

ToULongIntArray

Extracts an array of ULONGINT values from CVAR.

FUNCTION ToULongIntArray (BYVAL prgn AS ULONGINT PTR, BYVAL crgn AS ULONG) AS ULONG

Parameter	Description
prgn	Pointer to a buffer that contains crgn ULONGINT variables. When this function returns, the buffer has been initialized with UInt64 elements extracted from CVAR.
crgn	The number of elements in the buffer pointed to by prgn.

Return value

The count of UInt64 elements extracted from the CVAR.

Remarks

This helper function is used when the calling application expects a VARIANT to hold an array that consists of a fixed number of UInt64 values.

If the source VARIANT is of type VT_ARRAY OR VT_UI8, this function extracts up to crgn UInt64 values and places them into the buffer pointed to by prgn. If the VARIANT contains more elements than will fit into the prgn buffer, this function returns 0.

ToULongIntArrayAlloc

Extracts an array of ULONGINT values from CVAR.

FUNCTION ToULongIntArrayAlloc (BYVAL pprgn AS ULONGINT PTR PTR) AS ULONG

Parameter	Description
pprgn	Pointer to a ULONGINT PTR variable that will recive a pointer to an array of ULONGINT values extracted from the source CVAR.

Return value

The count of ULONGINT elements extracted from the CVAR.

Remarks

This helper function is used when the calling application expects a CVAR to hold an array of ULONGINT values.

If CVAR is of type VT_ARRAY OR VT_UI8, this function extracts an array of ULONGINT values into a newly allocated array. The calling application is responsible for using CoTaskMemFree to release the array pointed to by pprgn when it is no longer needed.

ToUShortArray

Extracts an array of UInt16 values from CVAR.

FUNCTION ToUShortArray (BYVAL prgn AS USHORT PTR, BYVAL crgn AS ULONG) AS ULONG

Parameter	Description
prgn	Pointer to a buffer that contains crgn UInt16 variables. When this function returns, the buffer has been initialized with UInt16 elements extracted from CVAR.
crgn	The number of elements in the buffer pointed to by prgn.

Return value

The count of UInt16 elements extracted from the CVAR.

Remarks

This helper function is used when the calling application expects a VARIANT to hold an array that consists of a fixed number of UInt16 values.

If the source VARIANT is of type VT_ARRAY OR VT_I2, this function extracts up to crgn UInt16 values and places them into the buffer pointed to by prgn. If the VARIANT contains more elements than will fit into the prgn buffer, this function returns 0.

ToUShortArrayAlloc

Extracts an array of USHORT values from CVAR.

FUNCTION ToUShortArrayAlloc (BYVAL pprgn AS USHORT PTR PTR) AS ULONG

Parameter	Description
pprgn	Pointer to a USHORT PTR variable that will recive a pointer to an array of USHORT values extracted from the source CVAR.

Return value

The count of USHORT elements extracted from the CVAR.

Remarks

This helper function is used when the calling application expects a CVAR to hold an array of USHORT values.

If CVAR is of type VT_ARRAY OR VT_UI2, this function extracts an array of SHORT values into a newly allocated array. The calling application is responsible for using CoTaskMemFree to release the array pointed to by pprgn when it is no longer needed.

ToUtf8

Returns the contents of a CVAR containing a BSTR as an UTF-8 encoded string.

FUNCTION ToUtf8 () AS STRING

Return value

The UTF-8 string.

ToVbDate

Returns the contents of a CVAR of type VT_DATE as a DATE value.

FUNCTION ToVbDate () AS DATE_

Return value

A DATE_ value (double).

ToWStr

Extracts the content of the underlying variant and returns it as a CWSTR.

FUNCTION ToWStr () AS CWSTR

Return value

The contents of the variant as a CWSTR.

Example

DIM cv AS CVAR = "Test string"
DIM cws AS CWSTR = cv.ToWStr

ValDouble

Converts the variant to a floating point number (DOUBLE)

FUNCTION ValDouble () AS DOUBLE

ValInt

Converts the variant to a signed 32-bit integer (LONG).

FUNCTION ValInt () AS LONG

ValLong

Converts the variant to a signed 32-bit integer (LONG).

FUNCTION ValLong () AS LONG

ValLongInt

Converts the variant to a signed 64-bit integer (LONGINT).

FUNCTION ValLongInt () AS LONGINT

Value

Converts the variant to a floating point number (DOUBLE).

FUNCTION Value () AS DOUBLE

ValUInt

Converts the variant to a 32.bit unsigned integer (ULONG).

FUNCTION ValUInt () AS ULONG

ValULong

Converts the variant to a 32.bit unsigned integer (ULONG).

FUNCTION ValULong () AS ULONG

ValULongInt

Converts the variant to a 64-bit unsigned integer (ULONGINT).

FUNCTION ValULongInt () AS ULONGINT

AfxCVarToStr

Extracts the contents of a CVAR to a CWSTR.

FUNCTION AfxCVarToStr OVERLOAD (BYREF cv AS CVAR) AS CWSTR

AfxCVarToStr

Extracts the contents of a CVAR to a CWSTR.

FUNCTION AfxCVarToStr OVERLOAD (BYVAL pcv AS CVAR PTR) AS CWSTR

AfxCVariantToBuffer

Extracts the contents of a variant that contains an array of bytes.

FUNCTION AfxCVariantToBuffer (BYREF cvIn AS CVAR, BYVAL pv AS LPVOID, BYVAL cb AS ULONG) AS ULONG

Parameter	Description
pv	Pointer to a buffer of length cb bytes. When this function returns, contains the first cb bytes of the extracted buffer value.
cb	The size of the pv buffer, in bytes. The buffer should be the same size as the data to be extracted, or smaller.

AfxCVarOptPrm

Returns a CVAR suitable to be used with optional parameters.

FUNCTION AfxCVarOptPrm () AS CVAR

Remarks

If you want to call a method that has optional variant parameters, you still have to pass the parameters, but in a way That the methods knows that they were omitted. Specifically, you have to pass them as type VT_ERROR, code DISP_E_PARAM_NOT_FOUND.

DIM v AS VARIANT = TYPE(VT_ERROR, 0, 0, 0, DISP_E_PARAMNOTFOUND)